Створення першого додатку
=========================

У цьому розділі ми розкажемо як створити наш перший додаток.
Для створення нового додатку будемо використовувати `yiic` (консольну утиліту), для
генерації коду — `Gii` (потужний веб кодогенератор). Будемо вважати для зручності,
що `YiiRoot` — це директорія, в яку встановлено Yii, а `WebRoot` — коренева
директорія вашего веб-серверу.

Запускаємо `yiic` у консолі з наступними параметрами:
~~~
% YiiRoot/framework/yiic webapp WebRoot/testdrive
~~~
> Note|Примітка: При використанні `yiic` на Mac OS,
> Linux або Unix вам може знадобитися змінити права доступу
> для файла `yiic`, щоб зробити його виконуваним.
> Альтернативний варіант запуску утиліти представлений нижче:
>
> ~~~
> % cd WebRoot
> % php YiiRoot/framework/yiic.php webapp testdrive
> ~~~

В результаті у директорії `WebRoot/testdrive` буде створений каркас додатку.

Створений додаток — хороша відправна точка для додавання необхідного функціоналу,
так як воно вже містить всі необхідні директорії та файли.
Не написавши жодного рядка коду, ми вже можемо протестувати 
наш перший Yii-додаток, перейшовши в браузері за наступним URL:

~~~
http://hostname/testdrive/index.php
~~~

Додаток містить чотири сторінки: головну, сторінку «про проект», 
сторінку зворотнього звʼязку та сторінку авторизації.
Сторінка зворотнього звʼязку містить форму для відправки питань та побажань, а сторінка авторизації
дозволяє користувачу аутентифікуватися та отримати доступ до закритої частини сайту (див. малюнки нижче).

![Головна сторінка](first-app1.png)

![Сторінка зворотнього звʼязку](first-app2.png)

![Сторінка зворотнього звʼязку з помилками вводу](first-app3.png)

![Сторінка зворотнього звʼязку з успішно відправленою формою](first-app4.png)

![Сторінка авторизації](first-app5.png)


Наш додаток має наступну структуру папок.
Детальний опис цієї структури можна знайти в [угодах](/doc/guide/basics.convention#directory).

~~~
testdrive/
    index.php                    скрипт ініціалізації додатку
    index-test.php               скрипт ініціалізації функціональних тестів
    assets/                      містить файли ресурсів
    css/                         містить CSS-файли
    images/                      містить зображення
    themes/                      містить теми оформлення додатку
    protected/                   містить захищені файли додатку
        yiic                     скрипт yiic
        yiic.bat                 скрипт yiic для Windows
        yiic.php                 PHP-скрипт yiic
        commands/                містить команди 'yiic'
            shell/               містить команди 'yiic shell'
        components/              містить компоненти для повторного використання
            Controller.php       класс базового контролеру
            UserIdentity.php     класс 'UserIdentity' для аутентифікації
        config/                  містить конфігураційні файли
            console.php          файл конфігурації консолі
            main.php             файл конфігурації веб-додатку
            test.php             файл конфігурації функціональних тестів
        controllers/             містить файли класів контролерів
            SiteController.php   класс контролеру за замовчуванням
        data/                    містить приклад бази даних
            schema.mysql.sql     схема БД для MySQL
            schema.sqlite.sql    схема БД для SQLite
            testdrive.db         файл БД для SQLite
        extensions/              містить сторонні розширення
        messages/                містить перекладені повідомлення
        models/                  містить файли класів моделей
            LoginForm.php        модель форми для дії 'login'
            ContactForm.php      модель форми для дії 'contact'
        runtime/                 містить тимчасові файли
        tests/                   містить тести
        views/                   містить файли представлень контролерів та файли макетів (layout)
            layouts/             містить файли представлень макетів
                main.php         загальна для всіх сторінок розмітка
                column1.php      розмітка для сторінок з одною колонкою
                column2.php      розмітка для сторінок з двома колонками
            site/                містить файли представлень для контролеру 'site'
                pages/           статичні сторінки
                    about.php    сторінка «про проект»
                contact.php      файл представлення для дії 'contact'
                error.php        файл представлення для дії 'error' (відображення помилок)
                index.php        файл представлення для дії 'index'
                login.php        файл представлення для дії 'login'
~~~

Описаний вище генератор додатку, також підтримує створення необхідних файлів для системи контролю версій Git.
Наступна команда створить необхідні файли `.gitignore` (наприклад, зміст директорій `assets` та `runtime` не повинен відслідковуватися)
та `.gitkeep` (примусово встановлює відстеження початково порожніх, але важливих каталогів):

~~~
% YiiRoot/framework/yiic webapp WebRoot/testdrive git
~~~

Інша система VCS, що підтримується, це Mercurial: передайте значення `hg` у якості третього параметра, якщо ви використовуєте цю VCS. 
Ця функція доступна із версії 1.1.11.

Зʼєднання з базою даних
-----------------------
Більшість веб-додатків використовують бази даних, і наш додаток не виключення. 
Для використання бази даних необхідно пояснити додатку, як до неї підключитися.
Це робиться у конфігураційному файлі `WebRoot/testdrive/protected/config/main.php`.
Наприклад, так:

~~~
[php]
return array(
	…
	'components'=>array(
		…
		'db'=>array(
			'connectionString'=>'sqlite:protected/data/testdrive.db',
		),
	),
	…
);
~~~

У наведеному вище коді вказано, що додаток повинен підключитися до бази даних SQLite
`WebRoot/testdrive/protected/data/testdrive.db` як тільки це знадобиться. Відмітимо, що
база даних SQLite вже вімкнена до згенерованого додатку. У цій базі є тільки
одна таблиця `tbl_user`:

~~~
[sql]
CREATE TABLE tbl_user (
	id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
	username VARCHAR(128) NOT NULL,
	password VARCHAR(128) NOT NULL,
	email VARCHAR(128) NOT NULL
);
~~~

Якщо ви бажаєте використовувати базу даних MySQL, ви можете використовувати файл
`WebRoot/testdrive/protected/data/schema.mysql.sql` для її створення.

> Note|Примітка: Для роботи з базою даних Yii потрібне розширення PHP PDO
і відповідний драйвер PDO. Для тестового додатку необхідно підключити
розширення `php_pdo` та `php_pdo_sqlite`.

Реалізація операцій CRUD
------------------------

А тепер найвеселіше. Ми б хотіли додати операції CRUD
(створення, читання, оновлення та видалениня) для щойно створеної таблиці `tbl_user` —
це часто необхідно при створенні реальних додатків. Замість написання коду ми
скористаємося веб-кодогенератором `Gii`.

> Info|Інформація: Gii доступний починаючи із версії 1.1.2. Раніше для тих же цілей
> використовувався вже згаданий `yiic`. Детальніше `yiic` описаний у розділі
«[генерація CRUD за допомогою yiic shell](/doc/guide/quickstart.first-app-yiic)».


### Налаштування Gii

Для того, щоб використовувати Gii, необхідно відредагувати
[файл конфігурації додатку](/doc/guide/basics.application#application-configuration)
`WebRoot/testdrive/protected/config/main.php`:

~~~
[php]
return array(
	…
	'import'=>array(
		'application.models.*',
		'application.components.*',
	),

	'modules'=>array(
		'gii'=>array(
			'class'=>'system.gii.GiiModule',
			'password'=>'впишіть свій пароль',
		),
	),
);
~~~

Після цього перейдіть по URL `http://hostname/testdrive/index.php?r=gii` та
введіть вказаний у конфігурації пароль.

### Генерація моделі User

Після входу перейдіть у розділ `Model Generator`:

![Model Generator](gii-model.png)

У полі `Table Name` введіть `tbl_user`. У полі `Model Class` — `User`.
Потім натисніть на кнопку `Preview`. Буде показаний новий файл, який буде
згенерировано. Після натискання кнопки `Generate` у `protected/models` буде створений
файл `User.php`. Як буде описано далі у керівництві, клас моделі `User`
дозволяє працювати з даними у таблиці `tbl_user` у стилі ООП.

### Генерація CRUD

Після генерації класів моделі ми згенеруємо код, який реалізує для неї операції CRUD.
Обираємо `Crud Generator`:

![CRUD Generator](gii-crud.png)

У полі `Model Class` вводимо `User`. У полі `Controller ID` — `user` (у нижньому регістрі).
Тепер натискаємо `Preview` і потім `Generate`. Генерація коду CRUD завершена.

### Доступ до сторінок CRUD

Давайте порадіємо нашим зусиллям, та перейдемо по URL:

~~~
http://hostname/testdrive/index.php?r=user
~~~

Ми бачимо сторінку із спиком користувачів із таблиці `tbl_user`. Оскільки наша таблиця пуста, то записів у ній не буде.
Кликнемо по кнопці `Create User` і, якщо ми ще не авторизовані, відобразиться сторінка авторизації.
Потім завантажиться форма додавання нового користувача. Заповнимо її та натиснемо кнопку `Create`.
Якщо при заповненні форми були допущені помилки, ми побачимо охайне повідомлення про помилку.

Повертаючись до списку користувачів, ми повинні побачити у списку щойно створенного користувача.
Додамо ще кілька користувачів. Зверніть увагу, що при значній
кількості користувачів для їх відображення на одній сторінці список буде автоматично розбиватися на сторінки.
Авторизувавшись у якості адміністратора (`admin/admin`),
можні побачити сторінку управління користувачами за адресою:

~~~
http://hostname/testdrive/index.php?r=user/admin
~~~

Зʼявиться охайна таблиця користувачів. Можна натиснути на заголовок
таблиці, щоб впорядкувати записи по значенням відповідного стовпця.
Для перегляду, редагування або видалення відповідного рядка можна
скористатися кнопками. Також можна переходити на різні сторінки, фільтрувати
результати та виконувати пошук по ним.

Все це не вимагає написання коду!

![Сторінка управління користувачами](first-app6.png)

![Сторінка додавання нового користувача](first-app7.png)